As soon as you scale-out your Spring Boot application (run with multiple instances) to e.g. increase throughput or availability, you have to ensure your application is ready for this architecture. Some parts of an application require tweaks before they fit for such an architecture. The use of @Scheduled tasks is a candidate for this. Most of the time, you only want this execution to happen on one instance and not in parallel. With this blog post, you'll learn how ShedLock can be used to only execute a scheduled task once for a Spring Boot application.

A lot of Spring Boot applications use the @Scheduled annotation to execute tasks regularly. Starting from simple reporting jobs every evening, over cleanup jobs, to synchronization mechanisms, the variety of use cases is huge.

As long as our application is running with one instance, there is no problem as the execution happens only once. But as soon as our application is deployed to a load-balanced environment where multiple instances of the same Spring Boot application are running in parallel, our scheduled jobs are executed in parallel.

In the case of reporting or synchronization, we might want to execute this only once for the whole application. By default, every instance would execute the scheduled task, regardless of whether or not any other instance is already running it. This might result in inconsistent data or duplicated actions.

Spring doesn’t provide a solution for running @Scheduled tasks on only one instance at a time out-of-the-box. This is where ShedLock comes into play as it solves this problem.

ShedLock is a distributed lock for scheduled tasks. It ensures to execute a task only once at the same time. Once the first instance acquires the lock for a scheduled task, all other instances will skip the task execution. As soon as the next task scheduling happens, all nodes will try to get the lock again.

ShedLock stores information about each scheduled job using persistent storage (so-called LockProvider) that all nodes connect to. There are multiple implementations for this LockProvider (e.g. for RDBMS, MongoDB, DynamoDB, Etcd, …) and we'll pick PostgreSQL as an example.

The database table that ShedLock uses internally to manage the locks is straightforward, as it only has four columns:

ShedLock creates an entry for every scheduled task when we run the task for the first time. From this point on the database row (one row for each job) is always present and will only be updated (not deleted and re-created).

The actual locking of a scheduled task happens by setting the lock_until column to a date in the future. As soon as a task is scheduled for execution, all application instances try to update the database row for this task. They are only able to lock the task if the task is currently not running (meaning lock_until